home
***
CD-ROM
|
disk
|
FTP
|
other
***
search
/
Language/OS - Multiplatform Resource Library
/
LANGUAGE OS.iso
/
cpp_libs
/
cool
/
ge_cool.lha
/
GE_COOL2.1
/
man
/
oldman3
/
Association.3T
next >
Wrap
Text File
|
1992-06-29
|
10KB
|
335 lines
.TH ASSOCIATION
.SH NAME
Association<Ktype,Vtype>\f1 A dynamic, parameterized association
.SH SYNOPSIS
#include <cool/Association.h>
.SH DESCRIPTION
The \f3Association<Ktype,Vtype>\f1 class is privately derived from the
\f3Vector<Type>\f1 class and implements a collection of pairs. The first of the pair
is called the
key ,
and the second of the pair is called the
value .
The
\f3Association<Ktype,Vtype>\f1 class implements a one-dimensional vector
parameterized over a pair of objects. The first type specifies the type of the
key, and the second type specifies the type of the value. Many of the member
functions for \f3Association<Ktype,Vtype>\f1 are inherited from \f3Vector<Type>\f1 and,
consequently, are inline calls to the vector member function of the same name.
.PP
The \f3Association<Ktype,Vtype>\f1 class inherits the dynamic growth capability of
the
Vector
class. Vectors are, by default, dynamic in nature. A static-sized
vector object is selected by setting the growth allocation size to zero or by
passing in a pointer to a block of user-supplied storage to the constructor. If
a vector is of static size and an operation is performed that requires more
storage, an
\f3\f3Error\f1\f1
exception is raised.
.PP
The \f3Association<Ktype, Vtype> \f1class implements the notion of a current
position. This is useful for iterating through the elements of a vector. The
current position is maintained in a data member of type
Association_state
and is set or reset by all member functions affecting elements in the class. Member
functions are provided to reset the current position, move to the next and
previous elements, find an element, and get the value at the current position.
The \f3Iterator<Type>\f1
class provides a mechanism to save and restore the state
associated with the current position, thus allowing the programmer to use
multiple iterators over the same instance of an association object.
.SH Base Classes
\f3Vector<Type>, Vector,
.SH Friend Classes
None
.SH Constructors
.TP
\f3Association<Ktype,Vtype> ();\f1
Creates an empty association of the specified type.
.TP
\f3Association<Ktype,Vtype> (const Association<Ktype,Vtype>& \f3assoc);\f1
Duplicates the size and value of an association object.
.TP
\f3Association<Ktype,Vtype> \f3(unsigned long \f2number);\f1
Allocates enough storage for an association of a specific type to hold
number
elements.
.TP
\f3Association<Type> (void* \f2storage\f3, unsigned long \f2number\f3);\f1
Creates a static-sized association object for
number
elements whose storage
storage
is provided by the user. If an object of this type attempts to grow
dynamically or the programmer invokes the
resize
member function, an
\f3\f3Error\f1\f1
exception is raised.
.SH Member Functions
.TP
inline long capacity ();
Returns the maximum number of elements the association can contain.
.TP
inline void clear ()
Removes all elements in the object and invalidates the current position.
.TP
inline Association_state& current_position ();
Returns the state information associated with the current position. This
function should be used with the \f3Iterator<Type>\f1 class to save and restore the
current position, thus facilitating multiple iterators over an instance of
association.
.TP
\f3Boolean find (const Ktype& key\f3);\f1
Searches the association for
key .
If found, this function sets the current
position and returns
TRUE ;
otherwise, this function resets the current position
and returns
FALSE .
.TP
\f3Boolean get (const Ktype& key, Vtype& value\f3);\f1
Gets the associated
value
for
key .
This function returns
TRUE
and modifies
value
to contain the associated value. If
key
is not found, this function
returns
FALSE
and does not modify
value .
.TP
\f3Boolean get_key (const Vtype& value, Ktype& key\f3) const;\f1
Gets the first associated
key
for
value .
This function returns
TRUE
and modifies
key
to contain the associated key. If
value
is not found, this
function returns
FALSE
and does not modify
key .
.TP
\f3inline const Ktype& \f3key () const;\f1
Returns the key of the key/value pair at the current position.
.TP
inline long length ();
Returns the number of elements (pairs) in the association.
.TP
inline Boolean next ();
Advances the current position pointer to the next element in the association
and returns
TRUE .
If the current position is invalid, this function advances to
the first element and returns
TRUE .
If advancing past the last element, this
function invalidates the current position and returns
FALSE .
.TP
\f3Association<Ktype,Vtype>& \f3operator= (const Association<Ktype,Vtype>>>&\f3);\f1
Overloads the assignment operator for the
Association
class and assigns one
association object to have the value of another by duplicating the size and
element values. This function invalidates the current position. If the
association is prohibited from dynamically growing as necessary, an
\f3\f3Error\f1\f1
exception is raised.
.TP
\f3Boolean operator== (const Association<Ktype,Vtype>& assoc\f3) const;\f1
Overloads the equality operator for the
Association
class. This function
returns
TRUE
if the associations have the same number of elements with the same
values; otherwise, this function returns
FALSE .
.TP
\f3inline Boolean operator!= (const Association<Ktype,Vtype>& assoc\f3) const;\f1
Overloads the inequality operator for the
Association
class. This function
returns
TRUE
if the associations have a different number of elements or
different values; otherwise, this function returns
FALSE .
.TP
inline Boolean prev ();
Moves the current position pointer to the previous element in the association
and returns
TRUE .
If the current position is invalid, this function moves to
the last element and returns
TRUE .
If moving to the previous element passes the
first element in the association, this function invalidates the current
position and returns
FALSE .
.TP
\f3Boolean put (const Ktype& key\f3, const Vtype& value\f3);\f1
Puts the
key/value
pair into the association. If a pair already exists with the
specified key, the value for that pair is replaced with
value .
If required and
not prohibited, the association is grown. If the new pair is successfully put
into the association,
TRUE
is returned; otherwise,
FALSE
is returned.
.TP
Vtype& remove ();
Removes and returns a reference to the element at the current position. This
function sets the current position to the element immediately following the
element removed. If the element removed is at the end of the association, this
function invalidates the current position. If the current position is invalid,
and
\f3\f3Error\f1\f1
exception is raised.
.TP
\f3Boolean remove (const Ktype& key\f3);\f1
Searches for
key
and, if found, this function removes the pair associated with
key
and sets the current position to the element immediately following the
element removed; then, the function returns
TRUE .
If
key
is found at the end of
the association, this function invalidates the current position and returns
TRUE .
If
key
is not found, this function returns
FALSE .
.TP
inline void reset ();
Invalidates the current position.
.TP
\f3inline void resize (long \f2number\f3);\f1
Resizes the association for at least
number
elements. If a growth ratio has
been selected and it satisfies the resize request, the association is grown by
this ratio. This function invalidates the current position. If the size
specified is zero or negative, an
\f3\f3Error\f1\f1
exception is raised.
.TP
\f3inline void set_alloc_size (int \f2size\f3);\f1
Updates the allocation growth size to be used when the growth ratio is zero.
Default allocation growth size is 100 bytes. If the size specified is
negative, an
\f3\f3Error\f1\f1
exception is raised.
.TP
\f3inline void set_growth_ratio (float \f2ratio\f3);\f1
Updates the growth ratio for this instance of an association to the specified
value. When an association needs to grow, the current size is multiplied by the
ratio to determine the new size. If
ratio
is negative, an
\f3\f3Error\f1\f1
exception is raised.
.TP
\f3void set_key_compare (\f2Assoc_Key_Compare \f3= NULL);\f1
Updates the key compare function for this class of association.
Assoc_Key_Compare
is a function of type
Boolean
(\f2*Function\f1)(\f3const Type&\f1, \f3const Type&\f1). If no argument is provided, the
operator==
for
Ktype
over which the key for the association class is parameterized is used.
.TP
\f3inline long set_length (long \f2number\f3);\f1
Specifies the
number
of elements in an association to allow random access via
the overloaded
operator[\^]
member function. If
number
is larger than the storage allocated, this function truncates
number
to the largest value the allocated size will support. This function returns the updated number of elements.
.TP
\f3void set_value_compare (\f2Assoc_Value_Compare \f3= NULL);\f1
Updates the value compare function for this class of association.
Assoc_Value_Compare
is a function of type
Boolean
(\f2*Function\f1)(\f3const Ktype&\f1, \f3const Vtype&\f1). If no argument is provided, the
operator==
for
Vtype
over which the value for the association class is parameterized is used.
.TP
inline Vtype& value ();
Returns a reference to the value of the key/value pair at the current position.
.SH Friend Functions
.TP
\f3friend ostream& operator<< (ostream& \f2os,\f3 const Association<Ktype,Vtype>& assoc\f3);\f1
Provides a formatted output capability for reference to an
\f3Association<Ktype,Vtype>\f1 object.
.TP
\f3inline friend ostream& operator<< (ostream& \f2os\f3, const Association<Ktype,Vtype>* assoc\f3);\f1
Provides a formatted output capability for a pointer to an
\f3Association<Ktype,Vtype>\f1 object.
.SH COPYRIGHT
Copyright (C) 1991 Texas Instruments Incorporated.
Permission is granted to any individual or institution to use, copy, modify,
and distribute this software, provided that this complete copyright and
permission notice is maintained, intact, in all copies and supporting
documentation.
Texas Instruments Incorporated provides this software "as is" without
express or implied warranty.